<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.10"/>
<title>axivdma: Main Page</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="HTML_custom.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectlogo"><img alt="Logo" src="xlogo_bg.gif"/></td>
  <td id="projectalign" style="padding-left: 0.5em;">
   <div id="projectname">axivdma
   </div>
   <div id="projectbrief">Xilinx SDK Drivers API Documentation</div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.10 -->
  <div id="navrow1" class="tabs">
    <ul class="tablist">
      <li class="current"><a href="index.html"><span>Overview</span></a></li>
      <li><a href="annotated.html"><span>Data&#160;Structures</span></a></li>
      <li><a href="globals.html"><span>APIs</span></a></li>
      <li><a href="files.html"><span>File&#160;List</span></a></li>
    </ul>
  </div>
</div><!-- top -->
<div class="header">
  <div class="headertitle">
<div class="title">axivdma Documentation</div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>This is the Xilinx MVI AXI Video DMA device driver. The DMA engine transfers frames from the AXI Bus or to the AXI Bus. It is in the chain of video IPs, which process video frames.</p>
<p>It supports the following features:</p><ul>
<li>Continuous transfers of video frames, AKA circular buffer mode</li>
<li>Continuous transfers of one specific video frame, AKA park mode</li>
<li>Optionally only transfer a certain amount of video frames</li>
<li>Optionally transfer unaligned frame buffers</li>
</ul>
<p>An AXI Video DMA engine can have one or two channels. If configured as two channels, then one of the channels reads data from memory, and the other channel writes to the memory.</p>
<p>For a full description of AXI Video DMA features, please see the hardware spec.</p>
<p>The driver composes of three parts: initialization, start a DMA transfer, and interrupt handling.</p>
<p><b> Driver Initialization </b></p>
<p>To initialize the driver, the caller needs to pass a configuration structure to the driver. This configuration structure contains information about the hardware build.</p>
<p>A caller can manually setup the configuration structure, or call XAxiVdma_LoopkupConfig().</p>
<p>The sequence of initialization of the driver is: 1. <a class="el" href="group__axivdma__v6__0.html#ga0188e06158c255eba62f52141cff5d84" title="Look up the hardware configuration for a device instance. ">XAxiVdma_LookupConfig()</a> to get the configuration structure, or manually setup the structure. 2. <a class="el" href="group__axivdma__v6__0.html#ga8d11c9609cf957c560fb287af1433374" title="Initialize the driver with hardware configuration. ">XAxiVdma_CfgInitialize()</a> to initialize the driver &amp; device. 3. <a class="el" href="group__axivdma__v6__0.html#gaf331929e09bf1454dc2835b6ecc4ff30" title="Set the number of frame store buffers to use. ">XAxiVdma_SetFrmStore()</a> to set the desired frame store number which is optional. 4. If interrupt is desired:</p><ul>
<li>Set frame counter using <a class="el" href="group__axivdma__v6__0.html#gaabe404c2a5c1483bc95be749c7540ba4" title="Set the frame counter and delay counter for both channels. ">XAxiVdma_SetFrameCounter()</a></li>
<li>Set call back functions for each channel. There are two types of call backfunctions: general and error</li>
<li>Enable interrupts that the user cares about</li>
</ul>
<p><b>Start a DMA Transaction </b></p>
<p>If you are using the driver API to start the transfer, then there are two ways to start a DMA transaction:</p>
<p>1. Invoke <a class="el" href="group__axivdma__v6__0.html#ga1dc126d885558e03cf06a4d9c05d5668" title="Start a write operation. ">XAxiVdma_StartWriteFrame()</a> or <a class="el" href="group__axivdma__v6__0.html#gab2646b6aeea2ff64c4b42319ffb49804" title="Start a read operation. ">XAxiVdma_StartReadFrame()</a> to start a DMA operation, depending on the purpose of the transfer (Read or Write).</p>
<p>2. Or, call the phased functions as the following:</p><ul>
<li>Call <a class="el" href="group__axivdma__v6__0.html#ga3c50e96d431d9f1ee7d6200266c0dbd3" title="Configure one DMA channel using the configuration structure. ">XAxiVdma_DmaConfig()</a> to set up a DMA operation configuration</li>
<li>Call <a class="el" href="group__axivdma__v6__0.html#ga8fa5b3e7978fda9bde7498a9d4af3c73" title="Configure buffer addresses for one DMA channel. ">XAxiVdma_DmaSetBufferAddr()</a> to set up the DMA buffers</li>
<li>Call <a class="el" href="group__axivdma__v6__0.html#gadf310ae3bd4c0ae9ebf3e445a2fbe444" title="Start one DMA channel. ">XAxiVdma_DmaStart()</a> to kick off the DMA operation</li>
</ul>
<p>If you are writing your own functions to start the transfer, the order of setting up the hardware must be the following:</p>
<ul>
<li>Do any processing or setting, but do not start the hardware, means do not set the RUN/STOP bit in the XAXIVDMA_CR_OFFSET register.</li>
<li>After any reset you need to do, write the head of your BD ring into the XAXIVDMA_CDESC_OFFSET register.</li>
<li>You can do other setup for the harware.</li>
<li>Start your hardware, by setting up the RUN/STOP bit in the XAXIVDMA_CR_OFFSET register.</li>
<li>You can do other setup for the hardware.</li>
<li>If you are done with all the setup, now write the tail of your BD ring to the XAXIVDMA_TDESC_OFFSET register to start the transfer.</li>
</ul>
<p>You can refer to <a class="el" href="group__axivdma__v6__0.html#ga3b9c24a02c4b4f99d40820a647de811d" title="Start a transfer. ">XAxiVdma_ChannelStartTransfer()</a> to see how this order is preserved there. The function is in <a class="el" href="xaxivdma__channel_8c.html">xaxivdma_channel.c</a>.</p>
<p>Note a Read VDMA could work with one out of multiple write VDMA instances and vice versa. The PointNum in structure <a class="el" href="struct_x_axi_vdma___dma_setup.html" title="The XAxiVdma_DmaSetup structure contains all the necessary information to start a frame write or read...">XAxiVdma_DmaSetup</a> decides which VDMA instance this VDMA is working with.</p>
<p><b>Interrupt Handling </b></p>
<p>Each VDMA channel supports 2 kinds of interrupts:</p><ul>
<li>General Interrupt: An interrupt other than error interrupt.</li>
<li>Error Interrupt: An error just happened.</li>
</ul>
<p>The driver does the interrupt handling, and dispatch to the user application through callback functions that user has registered. If there are no registered callback functions, then a stub callback function is called.</p>
<p>Each channel has two interrupt callback functions. One for IOC and delay interrupt, or general interrupt; one for error interrupt.</p>
<p><b>Reset</b></p>
<p>Reset a DMA channel causes the channel enter the following state:</p>
<ul>
<li>Interrupts are disabled</li>
<li>Coalescing threshold is one</li>
<li>Delay counter is 0</li>
<li>RUN/STOP bit low</li>
<li>Halted bit high</li>
<li>XAXIVDMA_CDESC_OFFSET register has 0</li>
<li>XAXIVDMA_TDESC_OFFSET register has 0</li>
</ul>
<p>If there is an active transfer going on when reset (or stop) is issued to the hardware, the current transfer will gracefully finish. For a maximum transfer length of (0x1FFF * 0xFFFF) bytes, on a 100 MHz system, it can take as long as 1.34 seconds, assuming that the system responds to DMA engine's requests quickly.</p>
<p>To ensure that the hardware finishes the reset, please use <a class="el" href="group__axivdma__v6__0.html#ga3e01bd69f101126d5962f7078ee3e520" title="This function checks one DMA channel for reset completion. ">XAxiVdma_ResetNotDone()</a> to check for completion of the reset.</p>
<p>To start a transfer after a reset, the following actions are the minimal requirement before setting RUN/STOP bit high to avoid crashing the system:</p>
<ul>
<li>XAXIVDMA_CDESC_OFFSET register has a valid BD pointer, it should be the head of the BD ring.</li>
<li>XAXIVDMA_TDESC_OFFSET register has a valid BD pointer, it should be the tail of the BD ring.</li>
</ul>
<p>If you are using the driver API to start a transfer after a reset, then it should be fine.</p>
<p><b>Stop</b></p>
<p>Stop a channel using XAxiVDma_DmaStop() is similar to a reset, except the registers are kept intact.</p>
<p>To start a transfer after a stop:</p>
<ul>
<li>If there are error bits in the status register, then a reset is necessary. Please refer to the <b>Reset</b> section for more details on how to start a transfer after a reset.</li>
<li>If there are no error bits in the status register, then you can call <a class="el" href="group__axivdma__v6__0.html#gadf310ae3bd4c0ae9ebf3e445a2fbe444" title="Start one DMA channel. ">XAxiVdma_DmaStart()</a> to start the transfer again. Note that the transfer always starts from the first video frame.</li>
</ul>
<p><b> Examples</b></p>
<p>We provide one example on how to use the AXI VDMA with AXI Video IPs. This example does not work by itself. To make it work, you must have two other Video IPs to connect to the VDMA. One of the Video IP does the write and the other does the read.</p>
<p><b>Cache Coherency</b></p>
<p>This driver does not handle any cache coherency for the data buffers. The application is responsible for handling cache coherency, if the cache is enabled.</p>
<p><b>Alignment</b></p>
<p>The VDMA supports any buffer alignment when DRE is enabled in the hardware configuration. It only supports word-aligned buffers otherwise. Note that "word" is defined by C_M_AXIS_MM2S_TDATA_WIDTH and C_S_AXIS_S2MM_TDATA_WIDTH for the read and write channel specifically.</p>
<p>If the horizonal frame size is not word-aligned, then DRE must be enabled in the hardware. Otherwise, undefined results happen.</p>
<p><b>Address Translation</b></p>
<p>Buffer addresses for transfers are physical addresses. If the system does not use MMU, then physical and virtual addresses are the same.</p>
<p><b>API Change from PLB Video DMA</b></p>
<p>We try to keep the API as consistent with the PLB Video DMA driver as possible. However, due to hardware differences, some of the PLB video DMA driver APIs are changed or removed. Two API functions are added to the AXI DMA driver.</p>
<p>For details on the API changes, please refer to <a class="el" href="xaxivdma__porting__guide_8h.html">xaxivdma_porting_guide.h</a>.</p>
<pre>
MODIFICATION HISTORY:</pre><pre>Ver   Who  Date     Changes
----- ---- -------- -------------------------------------------------------
1.00a jz   08/16/10 First release
2.00a jz   12/10/10 Added support for direct register access mode, v3 core
2.01a jz   01/19/11 Added ability to re-assign BD addresses
	      Replaced include xenv.h with string.h in <a class="el" href="xaxivdma__i_8h.html">xaxivdma_i.h</a>
		      file.
2.01a	rkv  03/28/11 Added support for frame store register and
                    XAxiVdma_ChannelInit API is changed.
3.00a srt  08/26/11 - Added support for Flush on Frame Sync and dynamic
		programming of Line Buffer Thresholds.</p><ul>
<li>XAxiVdma_ChannelErrors API is changed to support for
		Flush on Frame Sync feature.</li>
<li>Two flags, XST_VDMA_MISMATCH_ERROR &amp; XAXIVDMA_MIS
		MATCH_ERROR are added to report error status when
		Flush on Frame Sync feature is enabled.
4.00a srt  11/21/11 - XAxiVdma_ChannelSetBufferAddr API is changed to
		support 32 Frame Stores.</li>
<li>XAxiVdma_ChannelConfig API is changed to support
		modified Park Offset Register bits.</li>
<li>Added APIs:
		<a class="el" href="group__axivdma__v6__0.html#gaa3376589f8781eec1f0d619e1a0d3078" title="Configure Frame Sync Source and valid only when C_USE_FSYNC is enabled. ">XAxiVdma_FsyncSrcSelect()</a>
		<a class="el" href="group__axivdma__v6__0.html#gacf7ed6b0ef406b80e49ff25634f6d5f1" title="Configure Gen Lock Source. ">XAxiVdma_GenLockSourceSelect()</a></li>
<li>Modified structures <a class="el" href="struct_x_axi_vdma___config.html" title="This typedef contains the hardware configuration information for a VDMA device. ">XAxiVdma_Config</a> and <a class="el" href="struct_x_axi_vdma.html" title="The XAxiVdma driver instance data. ">XAxiVdma</a> to
	        include new parameters.
4.01a srt  06/13/12 - Added APIs:
		<a class="el" href="group__axivdma__v6__0.html#ga4d93d3dea2f117948c175371d983a0e1" title="Check for DMA Channel Errors. ">XAxiVdma_GetDmaChannelErrors()</a>
		<a class="el" href="group__axivdma__v6__0.html#gac01b1199d15a3a95cafb01f61dd1d0d3" title="Clear DMA Channel Errors. ">XAxiVdma_ClearDmaChannelErrors()</a>
		XAxiVdma_ClearChannelErrors()</li>
<li>XAxiVdma_ChannelErrors API is changed to remove
		Mismatch error logic.</li>
<li>Removed Error checking logic in the channel APIs.
		Provided User APIs to do this.</li>
<li>Added new error bit mask XAXIVDMA_SR_ERR_SOF_LATE_MASK</li>
<li>XAXIVDMA_MISMATCH_ERROR flag is deprecated.<ul>
<li>Modified the logic of Error handling in interrupt
	        handlers.
4.02a srt  10/11/12 - XAxiVdma_SetFrmStore function changed to remove
                      Reset logic after setting number of frame stores.
		(CR 678734)</li>
</ul>
</li>
<li>Changed Error bitmasks to support IP version 5.02a.
		(CR 679959)
4.03a srt  01/18/13 - Updated logic of GenLockSourceSelect() &amp; FsyncSrcSelect()
                      APIs for newer versions of IP (CR: 691052).</li>
<li>Modified CfgInitialize() API to initialize
		StreamWidth parameters and added TDATA_WIDTH parameters
		to tcl file (CR 691866)</li>
<li><p class="startli">Updated DDR base address for IPI designs (CR 703656).
4.04a srt  03/03/13 - Support for the GenlockRepeat Control bit (Bit 15)
                      added in the new version of IP v5.04 (CR: 691391)</p>
<ul>
<li>Updated driver tcl, <a class="el" href="xaxivdma__g_8c.html">xaxivdma_g.c</a> and  <a class="el" href="struct_x_axi_vdma___config.html" title="This typedef contains the hardware configuration information for a VDMA device. ">XAxiVdma_Config</a>
		structure in <a class="el" href="xaxivdma_8h.html">xaxivdma.h</a> to import the relevant VDMA IP
		DEBUG_INFO_* parameters into the driver.
		This fixes CR# 703738.
4.05a srt  05/01/3  - Merged v4.03a driver with v4.04a driver.
	             Driver v4.03a - Supports VDMA IPv5.04a XPS release
	             Driver v4.04a - Supports VDMA IPv6.00a IPI release
                       The parameters C_ENABLE_DEBUG_* are only available in
	         VDMA IPv6.00a. These parameters should be set to '1'
	         for older versions of IP (XPS) and added this logic in
	         the driver tcl file.<ul>
<li>Added unalignment checks for Hsize and Stride
		(CR 710279)
4.06a srt  04/09/13 - Added support for the newly added S2MM_DMA_IRQ_MASK
                      register (CR 734741)
5.0   adk  19/12/13 - Updated as per the New Tcl API's
5.1   adk  20/01/15  Added support for peripheral test. Created the self
	       test example to include it on peripheral test's(CR#823144).
5.1   adk  29/01/15  Added the sefltest api (XAxiVdma_Selftest) to the driver source files
                    (<a class="el" href="xaxivdma__selftest_8c.html">xaxivdma_selftest.c</a>) and called this from the selftest example
6.0   vak  27/07/15  Added example for demonstarting triple buffer api.
6.0   vak  27/07/15  Added 64 bit addressing support to the driver.
6.0   vak  26/08/15  Added checks to align hsize and stride based on channel direction
                     (read or write)(CR 874861)</li>
</ul>
</li>
</ul>
</li>
</ul>
</pre><pre></pre> </div></div><!-- contents -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="footer">Copyright &copy; 2015 Xilinx Inc. All rights reserved.</li>
  </ul>
</div>
</body>
</html>
